﻿using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Streambolics
{
    /// <summary>
    ///     An object that is able to provide a real-time data reading.
    /// </summary>
    /// <remarks><para>
    ///     Real time data producers, as usual, are polled instead of generating
    ///     events.
    /// </para><para>
    ///     Tools for implementing real time data producers should be located in
    ///     the Tct namespace.
    /// </para></remarks>

    public interface IRealTimeDataProducer
    {
        /// <summary>
        ///     Acquire the new real time value.
        /// </summary>
        /// <param name="aValue">
        ///     The acquired value. Not relevant if the method returns false.
        /// </param>
        /// <param name="aTimeStamp">
        ///     The timestamp of the acquired value.
        /// </param>
        /// <returns>
        ///     True if a new data value is available (in which case aValue and aTimeStamp have received the value.)
        ///     False if no new data value was available, in which case aValue and aTimeStamp have undefined values.)
        /// </returns>
        /// <remarks><para>
        ///     The method must return True whenever a new value has been acquired, even if that value is the same as
        ///     the previously acquired value. For example, assume a sensor that computes the free space on a disk
        ///     drive once every minute.
        ///     <list type=""><item>
        ///         The GetRealTimeData method is called for the first time. Since it's the first time, the free space
        ///         is computed (assume it's exactly 10GB.) The method returns true, sets aValue to 10 billion and aTimeStamp
        ///         to Now.
        ///     </item><item>
        ///         The GetRealTimeDate method is called 30 seconds later. Since the sensor only retrieves the value every
        ///         minute, it returns false.
        ///     </item><item>
        ///         The GetRealTimeData method is called again, 30 more seconds later. This time, one minute has elapsed,
        ///         so the sensor reads the free disk space, finds it to be exactly the same value 10 billion.
        ///         The method should return true, since a new value has been acquired, even though it is the same value as
        ///         before.
        ///     </item></list>
        /// </para></remarks>

        bool GetRealTimeData (out double aValue, out DateTime aTimeStamp);
    }
}
